content/docs/how-to/sign-component-version.md (1)

21-24: Inconsistent relref path prefixes.

Line 21 uses "ocm-cli-installation.md" without the docs/ prefix, while lines 22-23 include the docs/ prefix. This inconsistency may cause broken links.

🔗 Standardize to full paths

-- [OCM CLI installed]({{< relref "ocm-cli-installation.md" >}})
+- [OCM CLI installed]({{< relref "docs/getting-started/ocm-cli-installation.md" >}})

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/sign-component-version.md` around lines 21 - 24, Update
the inconsistent relref in the checklist so all links use the same path style:
change the first entry referencing "ocm-cli-installation.md" to include the
"docs/" prefix to match the other two links (so the three relref targets become
"docs/ocm-cli-installation.md", "docs/how-to/generate-signing-keys.md", and
"docs/how-to/configure-signing-credentials.md"); ensure the visual text labels
remain unchanged and verify links render correctly after the change.

content/docs/how-to/verify-component-version.md (2)

17-19: Inconsistent relref path prefixes.

Line 17 uses "ocm-cli-installation.md" without the docs/ prefix, while line 18 uses "docs/how-to/configure-signing-credentials.md" with the prefix. This inconsistency could cause broken links depending on Hugo's configuration.

🔗 Standardize relref paths

-- [OCM CLI installed]({{< relref "ocm-cli-installation.md" >}})
+- [OCM CLI installed]({{< relref "docs/getting-started/ocm-cli-installation.md" >}})

Standardizing all paths to use the full path from docs/ will make link resolution more predictable.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/verify-component-version.md` around lines 17 - 19, The
relref paths are inconsistent: change the first link target
"ocm-cli-installation.md" to the full path "docs/ocm-cli-installation.md" so it
matches the other relref ("docs/how-to/configure-signing-credentials.md");
update the relref in the list (the entry referencing OCM CLI) to use the
"docs/..." prefix to standardize link resolution across the document.

---

85-86: Consider using more robust YAML querying.

The grep -A 10 signatures: approach is fragile and may not work correctly if the YAML structure varies.

🛠️ Use yq or jq for structured YAML querying

If yq is available:

ocm get cv ./transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml | yq '.signatures'

Or extract just signature names:

ocm get cv ./transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml | yq '.signatures[].name'

However, this requires users to have yq installed, so the current grep approach may be intentionally simple for accessibility.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/verify-component-version.md` around lines 85 - 86, The
inline grep usage "ocm get cv
./transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml | grep -A 10
signatures:" is fragile; replace it with structured YAML querying using yq or jq
to reliably extract the signatures field (for example, query the .signatures
node or iterate .signatures[].name) and document both the yq/jq commands as the
preferred approach and the simple grep fallback for users without those tools so
the README shows a robust and an accessible option.

content/docs/tutorials/signing-and-verification.md (1)

223-230: Consider clarifying the tampering test behavior.

Lines 226 and 229 include commands that may not behave as documented:

1. Line 226: 2>/dev/null || true suppresses all errors, making it unclear if the resource addition succeeded or failed
2. The comment says "should fail if the descriptor changed" but the test's behavior depends on whether the resource addition actually modified the component

🧪 Make tampering test more explicit

-# Add a new resource (this changes the component descriptor)
-echo "malicious content" > /tmp/evil.txt
-ocm add resource ./transport-archive//github.com/acme.org/helloworld:1.0.0 \
-  --name evil --type plainText --input-file /tmp/evil.txt 2>/dev/null || true
+# Add a new resource to change the component descriptor
+echo "tampered content" > /tmp/tampered.txt
+if ocm add resource ./transport-archive//github.com/acme.org/helloworld:1.0.0 \
+  --name tampered --type plainText --input-file /tmp/tampered.txt; then
+  echo "✓ Component modified - signature should now be invalid"
+else
+  echo "⚠ Note: Resource addition may have failed, try re-signing if verification still passes"
+fi
 
-# Try to verify (should fail if the descriptor changed)
-ocm verify cv ./transport-archive//github.com/acme.org/helloworld:1.0.0
+# Verification should now fail because the component changed after signing
+if ocm verify cv ./transport-archive//github.com/acme.org/helloworld:1.0.0; then
+  echo "⚠ Unexpected: Verification passed despite tampering"
+else
+  echo "✓ Expected: Verification failed, tampering detected"
+fi

However, the current simpler approach may be intentional for tutorial readability.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/tutorials/signing-and-verification.md` around lines 223 - 230,
The tampering test hides whether the malicious resource was actually added
because the `ocm add resource
./transport-archive//github.com/acme.org/helloworld:1.0.0 --name evil --type
plainText --input-file /tmp/evil.txt 2>/dev/null || true` command suppresses
errors; update the tutorial to run the `ocm add resource` command without
redirecting stderr and without `|| true` (or add an explicit check of its exit
status and/or inspect the component descriptor after the add) and then keep the
`ocm verify cv ./transport-archive//github.com/acme.org/helloworld:1.0.0` step,
while also clarifying the comment to say “verify should fail if the component
descriptor was actually modified by the previous add” so readers know to ensure
the add succeeded before expecting verification to fail.

content/docs/how-to/sign-component-version.md (1)

82-92: ⚠️ Potential issue | 🟡 Minor

Fix algorithm field in YAML example to match OCM documentation.

The example uses algorithm: RSA/PKCS1v15, but OCM documentation consistently shows RSASSA-PSS (default) or RSASSA-PKCS1V15. Update line 90 to use one of these standard algorithm names.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/sign-component-version.md` around lines 82 - 92, The YAML
example's signature.algorithm value is non-standard; update the
signature.algorithm field in the example (under the signatures -> signature
mapping) to use a standard OCM algorithm name such as "RSASSA-PSS" (preferred)
or "RSASSA-PKCS1V15" instead of "RSA/PKCS1v15" so it matches OCM documentation
and other examples.

content/docs/how-to/configure-signing-credentials.md (1)

200-201: ⚠️ Potential issue | 🟡 Minor

Fix broken CLI reference links.

The links to CLI reference documentation (/docs/reference/ocm-cli/ocm_sign_component-version.md and ocm_verify_component-version.md) reference files that do not exist according to past review findings.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/configure-signing-credentials.md` around lines 200 - 201,
The CLI reference links in the table for the commands `ocm sign cv --dry-run`
and `ocm verify cv` point to non-existent files (`ocm_sign_component-version.md`
and `ocm_verify_component-version.md`); update the relref targets to the correct
existing reference pages (or remove/replace with the correct canonical
filenames) by editing the table rows containing those commands so the `{{<
relref ... >}}` values reference the actual docs filenames for the ocm sign and
ocm verify CLI commands (verify the real filenames in the reference directory
and use those names in place of `ocm_sign_component-version.md` and
`ocm_verify_component-version.md`).

content/docs/how-to/configure-credentials-ocm-controllers.md (1)

311-311: ⚠️ Potential issue | 🟡 Minor

Fix broken link references to non-existent file.

The referenced file creds-in-ocmconfig.md does not exist in the current documentation structure according to past review findings. Either restore this file or update the reference to point to an existing file.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/how-to/configure-credentials-ocm-controllers.md` at line 311,
The markdown link "[How-To: Configure Credentials for Multiple Registries]({{<
relref \"creds-in-ocmconfig.md\" >}})" points to a non-existent file; fix by
either restoring the missing creds-in-ocmconfig.md page or updating the relref
target to the correct existing doc (e.g., the actual how-to page that covers
configuring credentials in .ocmconfig). Locate the exact link string in the file
and replace the relref argument with the correct filename (or remove the link
and leave plain text) so that the documentation builds without broken
references.

content/docs/tutorials/signing-and-verification.md (1)

296-307: Consider using consistent relref path format within the document.

Lines 298-301 use short format ({{< relref "filename.md" >}}), while lines 305-307 use full path format ({{< relref "docs/path/filename.md" >}}). While both formats are acceptable and work correctly in Hugo, using a consistent style within the same document improves maintainability.

♻️ Suggested consistency improvement

Option 1: Use short format throughout (if filenames are unique):

 ## Related Documentation
 
-- [Concept: Signing and Verification]({{< relref "docs/concepts/signing-and-verification-concept.md" >}}) - Understand the theory behind OCM signing
-- [How-to: Generate Signing Keys]({{< relref "docs/how-to/generate-signing-keys.md" >}}) - Detailed key generation guide
-- [How-to: Configure Signing Credentials]({{< relref "docs/how-to/configure-signing-credentials.md" >}}) - Multi-environment and advanced configurations
+- [Concept: Signing and Verification]({{< relref "signing-and-verification-concept.md" >}}) - Understand the theory behind OCM signing
+- [How-to: Generate Signing Keys]({{< relref "generate-signing-keys.md" >}}) - Detailed key generation guide
+- [How-to: Configure Signing Credentials]({{< relref "configure-signing-credentials.md" >}}) - Multi-environment and advanced configurations

Option 2: Use full path format throughout:

 ## Next Steps
 
-- [How-to: Generate Signing Keys]({{< relref "generate-signing-keys.md" >}}) - Step-by-step creating RSA key pairs.
-- [How-to: Configure Signing Credentials]({{< relref "configure-signing-credentials.md" >}}) - Set up OCM to use your keys for signing and verification
-- [How-to: Sign a Component Version]({{< relref "sign-component-version.md" >}}) - Step-by-step signing instructions
-- [How-to: Verify a Component Version]({{< relref "verify-component-version.md" >}}) - Step-by-step verification instructions
+- [How-to: Generate Signing Keys]({{< relref "docs/how-to/generate-signing-keys.md" >}}) - Step-by-step creating RSA key pairs.
+- [How-to: Configure Signing Credentials]({{< relref "docs/how-to/configure-signing-credentials.md" >}}) - Set up OCM to use your keys for signing and verification
+- [How-to: Sign a Component Version]({{< relref "docs/how-to/sign-component-version.md" >}}) - Step-by-step signing instructions
+- [How-to: Verify a Component Version]({{< relref "docs/how-to/verify-component-version.md" >}}) - Step-by-step verification instructions

Based on learnings, both relref formats are acceptable in this repository and Hugo resolves unique filenames without a path prefix.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/tutorials/signing-and-verification.md` around lines 296 - 307,
The relref links in the "Next Steps" and "Related Documentation" sections are
inconsistent: some use short form (e.g., {{< relref "generate-signing-keys.md"
>}}) while others use full path form (e.g., {{< relref
"docs/how-to/generate-signing-keys.md" >}}); pick one style (prefer the short
form if filenames are unique) and update the occurrences for the files
referenced—generate-signing-keys.md, configure-signing-credentials.md,
sign-component-version.md, verify-component-version.md, and
signing-and-verification-concept.md—to use the chosen relref format consistently
throughout the document.

content/docs/concepts/signing-and-verification-concept.md (1)

66-74: ⚠️ Potential issue | 🟠 Major

Resolve digest algorithm inconsistency for OCI artifacts.

The table says OCI artifacts use ociArtifactDigest/v1, but your later ociImage example uses genericBlobDigest/v1 (Lines 130–140). Please make this consistent with the intended current behavior to avoid incorrect signing mental models.

#!/bin/bash
# Verify current algorithm usage consistency across docs
rg -n "ociArtifactDigest/v1|genericBlobDigest/v1|normalisationAlgorithm" content/docs/ -C2

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/concepts/signing-and-verification-concept.md` around lines 66 -
74, The docs are inconsistent: the table declares the OCI algorithm as
ociArtifactDigest/v1 but the ociImage example uses genericBlobDigest/v1; update
the ociImage example to use ociArtifactDigest/v1 (or alternatively change the
table if you intended genericBlobDigest/v1) so both the table and the ociImage
example reference the same algorithm; search for and replace occurrences in the
ociImage example and any related examples or references to
normalisationAlgorithm to ensure all examples consistently use
ociArtifactDigest/v1.

content/docs/tutorials/signing-and-verification.md (1)

86-89: ⚠️ Potential issue | 🔴 Critical

Fix broken tutorial command: ocm add cv is incomplete.

This step cannot run as written and blocks the tutorial flow. Add the required arguments (archive target + constructor) so it actually creates the sample CV.

Suggested fix

-# Create component version in a CTF archive located at ./transport-archive
-ocm add cv 
+# Create component version in a CTF archive located at ./transport-archive
+ocm add cv ./transport-archive --constructor component-constructor.yaml

#!/bin/bash
# Compare known working `ocm add cv` command patterns in docs
rg -nP '\bocm\s+add\s+cv\b' content/docs/ -C2

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/docs/tutorials/signing-and-verification.md` around lines 86 - 89, The
tutorial's step uses an incomplete command "ocm add cv" which needs both the
archive target and a constructor reference; update that line to call "ocm add
cv" with the target archive "./transport-archive" and a valid constructor
argument (for example add "--constructor <constructor-ref>" or supply the
component identity/version) so the command actually creates the sample component
version in the CTF archive.

.github/config/wordlist.txt (1)

462-476: Consider inserting new wordlist entries in alphabetical order.

The new entries appear to be added near the end of the file rather than in their proper alphabetical positions. While the file functions correctly either way, maintaining alphabetical order improves maintainability by making it easier to verify whether a term already exists and to spot duplicates.

For reference, the proper positions would be:

• centos → after line 28 (after "cest")
• dockerconfigjson → after line 102 (after "dockerconfig")
• helloworld → after line 169 (after "helmrepository")
• href → after line 173 (after "hostpath")
• iam → after line 177 (after "iaas")
• misattributed → after line 234 (after "mimetype")
• ocirepository → after line 266 (after "ocireg")
• rhel → after line 322 (after "resendbuffer")
• whitespace → after line 410 (after "wget")
• xdg → after line 413 (after "xml")
• hsms → after line 443 (after "hsm")

📝 Script to verify proper alphabetical ordering

#!/bin/bash
# Check if the wordlist is properly sorted
sort -c .github/config/wordlist.txt 2>&1 || echo "File is not sorted. Run 'sort -o .github/config/wordlist.txt .github/config/wordlist.txt' to fix."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/config/wordlist.txt around lines 462 - 476, The added wordlist
entries (href, dockerconfigjson, rhel, misattributed, whitespace, hsms,
helloworld, centos, wsl, auditable, hasmermaid, xdg, subpaths, iam,
ocirepository) were appended out of alphabetical order; reorder them into their
correct alphabetic positions (e.g., insert centos after "cest", dockerconfigjson
after "dockerconfig", helloworld after "helmrepository", href after "hostpath",
iam after "iaas", misattributed after "mimetype", ocirepository after "ocireg",
rhel after "resendbuffer", whitespace after "wget", xdg after "xml", hsms after
"hsm") or simply run a stable sort of the entire .github/config/wordlist.txt to
restore proper ordering and avoid duplicates.